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PART 1 


AN IMPROVED APPROACH TO TRACE ROUTINES 


INTRODUCTION 

Analyzing the flow of executed computer programs is among the most funda- 
mental and essential techniques of debugging. With increasing sophistication 
in both computer hardware and software determining program flow is becoming 
progressively more difficult. Complicating factors are address indexing, in- 
direct addressing, automatic allocation of relocatable subroutines, a wealth of 
resident monitor and library routines, chaining, and both manual and automatic 
overlay facilities. 

The classic approach to unwinding these factors and presenting useful diag- 
nostic information to the program has been and will continue to be — at least for 
the foreseeable future - the use of trace programs. Through the use of hard- 
ware interrupts and interpretive software routines, changes in sequential ad- 
dressing of computer programs by jumps (branches) and tests (compares) can 
be detected, interpreted, and reported to the programmer. 

Problems 


Despite the value of trace routines, several serious drawbacks have de- 
terred programmers from their use. Perhaps the worst of these are consider- 
ably extended execution time and overabundance of printed diagnostic material. 
Among the secondary problems is the inability of users to provide "own- coding” 
subroutines for extended usage. 

This document proposes a solution to these problems. It also describes 
usage of the trace routine embodying these improvements for the Univac 1107. 

Option Control 


Increasing the speed and efficiency of trace programs can be approached 
on two fronts: first, application of utmost skill and ingenuity in developing the 
routine; second, allowing flexible control of option-subroutines to eliminate 
unwanted processing. The former approach will not be discussed because it is 
ultimately limited by hardware; the latter approach however, is limited only by 
imagination. 
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When developing a routine, a systems analyst first asks, "What should it 
do?" Partial answers come from the historic solutions to similar problems; 
further answers are obtained by polling likely users of the routine for recom- 
mendations. Generally, the analyst cannot obtain agreement without devising 
a system encompassing all options. Such a task is burdensome not only to the 
developer, but to the user as well. Furthermore, it defies speed and efficiency. 

Enigmatically a solution to option control is to eliminate all but one option: 
that is, to allow the use of arbitrary externally defined subroutines which are 
callable by the trace routine. For discussion purposes, such a subroutine will 
be termed a s ubservient . 

The trace routine can be written to leave the same basic information avail- 
able to all subservients. Normally this will be the origin and destination ad- 
dresses representing a change in sequential addressing, and will be called a 
FROM-TO address pair. In this manner all subservients can be independent. 

It is now possible to construct a basic set of subservients, each performing a 
unique function. In addition, any subservient can be called by another, so that 
a composite of functions can be selected to fulfill a required task. 

The advantage of this procedure from a user's standpoint is that he himself 
can select a subservient for his problem. In the simplest case, he can request a 
single subservient made available on a standard library; in this instance, no cod- 
ing is required. In a more advanced situation, he may wish to construct his own 
subservient, consisting of imbedded calls to any number of library subservients. 
Thus, only those required components are executed. Also, no option-testing 
logic is necessary, as the user has coded these options into his own subservient. 

Minimization ol Printing 

When using most print options in a trace program, the user often finds him- 
self surrounded with paper. Also, it is likely that exaggerated execution time or 
high print load has prevented him from reaching the conditions he wants traced. 
Even if these conditions were encountered, mechanical problems of shuffling 
paper may discourage him from further pursuits. Circumstances such as these 
often cause a trace routine to be relegated to a position of secondary importance. 

An initial step to an effective solution is to eliminate printing for all but 
the most essential information, the FROM-TO address pairs. Such a decision 
is not too severe because the ability to construct and nest subservients allows 
the user to reconstruct reports of more exacting information. Also, as will be 
favored by some computer installations, this approach places the heaviest 
burden on those programmers requiring the most demanding printouts, but 
does not penalize the average user. Unfortunately, adoption of this initial step 
is not entirely adequate in resolving the problem of sheer paper volume. 
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If it were possible, the most desirable solution would be to avoid printing 
completely. Perhaps the next best alternative is to retain trace information in 
a core table for selective printing at the end of the job. In reality, however, few 
tables would be extensive enough to retain significant data; core would speedily 
become exhausted. 

Despite apparent problems development of an adequate core table is still 
practicable. By storing cyclically in the table — overlaying from top to bottom — 
a fixed amount of data is maintained. In addition, only the most recent address 
pairs are left available because predecessors for each position in the table have 
been overstored. This constant updating will continue until tracing is terminated 
by user request, normal end of job, or abnormal end of job. The import of this 
data at abnormal completion is obvious. 

To help offset limitations imposed by a cyclic table, options can be pro- 
vided which allow the user to establish the length of this table. Also, enhance- 
ments can be provided for efficient use of the table: for example, a repeat 
count for iterated address pairs can optimize storage by compressing the data. 

Finally, it is necessary to pi’int the table. As this now occurs after pro- 
gram execution, various post mortem routines are usually available in utility 
packages to provide this core dump. Characteristically, such routines maxi- 
mize output on the printed line, provide reasonable options for format control, 
and operate efficiently. A combination like this is usually more than adequate 
for programmer needs. 

Extended Usage 


Knowing all subservients are furnished with the same FROM- TO address 
pair information, the user can code and nest virtually any special trace tech- 
niques he desires. A variety of library and resident monitor subroutines is 
generally available to assist him. Among the most significant applications for 
the trace routine described in Section II are: 

1. Dynamic dumping of arbitrarily selected memory locations at the time 
of each traced instruction 

2. Continuous testing for jumps (branches) to illegal destinations, and 
execution of an error routine for these events 

3. Continuous testing to detect which instruction or I/O operation is over- 
storing specific cells in memory, and execution of an error routine for 
these events 
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4. Computation of the distribution of operation codes in an executing pro- 
gram, including - at the user's discretion - library and resident monitor 
routines 

5. Continuous detection and logging of points where characteristic overflow, 
characteristic underflow, divide overflow, occur 

6. Various combinations of the above practices 

Note that no modifications, other than a call to the trace routine, are needed 
to apply these techniques to existing programs. 
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PART II 


A TRACE ROUTINE FOR THE UNIVAC 1107 


INTRODUCTION 

The trace routine is a blend between a software and hardware trace. Soft- 
ware components are necessary to allow for restoring register R3 after a trace 
interrupt occurs. They also permit establishing the locations of all executed 
JMGI/MOJP (not provided by a trace interrupt) and of all instructions perform- 
ing a skip. Hardware components of this routine are used solely for detecting 
that a jump instruction was executed, for obtaining the address to which control 
was to be transferred, and for returning control to the trace routine. 

Sleuth H Calling Sequences 


In general, the SLEUTH II calling sequence for initiating trace is: 


LMJ 

+ 

+ 

+ 


11, TRC$ 

interrupt routine entry point, mode 
lower core limit, upper core limit 

address of trace storage table, length of table (dependent) 


Parameters are interpreted as follows: 

Mode: value 0 means trace jumps only 

value 1 means trace jumps and skips only 
value 2 means trace all instructions 


Interrupt routine entry point: Starting line of routine to which control is 
transferred after detecting a condition determined by the selected mode. 
Upon entry to this routine , A0 will contain the address of the jump or 
skip; A1 will contain the address for the next sequential instruction. 
Entry to the interrupt routine is made by an SLJ instruction. 

Upper and lower core limits: Core limits in which the trace is permitted 
to report to the interrupt routine. 

Address of trace storage table, length of table: These parameters are 
needed only when using standard interrupt routines described later. 
These routines develop tables of trace information in user-defined core 
regions. 
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All tracing is terminated by the calling sequence 
LMJ 11, TRCX$ 

Re-entry without reinitialization to the last trace function is by 

LMJ 11, TRCR$ 

The procedures equivalent to these calls are: 

T$RC interrupt routine entry point, mode 

lower core limit, upper core limit 

address of trace storage table, length of table 

T$RCX 

T$RCR 

The General Interrupt Routine Facility 


By supplying a label to his own routine, the user can process all traced in- 
structions that occur with either the FROM or TO address in his designated core 
limits. These addresses are available to him in A 0 and A1 respectively. (The 
contents of A0 and A1 before trace interrupt occurred may be found in cells 
TRCA0$ and TRCA1$) If registers other than A0 and A1 are used in the inter- 
rupt routine, they must be saved and restored by the user before returning 
control. Entry to the interrupt routine is made by an SLJ instruction. 


The calling sequence for this routine is: 


LMJ 

11, TRC$ 

+ 

routine name, tract mode of 0, 1, or 2 

+ 

lower core limit, upper core limit 

T$RC 

routine name , mode 

lower core limit, upper core limit 

The TRCY$ Standard Interrupt Routine 


This routine stores information into a user- specified storage table. Stor- 
age is made cyclically; that is, once the area is filled, overlaying will occur 
from the top. A single negative zero is placed after the last written value to 
signal a division between the old area and the new. 

When either the traced FROM address or TO address is within the desig- 
nated core limits, an address pair in the format +(FROM, TO) is inserted in 
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the table. However, if this address pair is identical to the previous pair, a re- 
peat count, N, is developed and stored instead. This is identified by the format 
(- 0 , N). 

If a call to TRCY$ is made via T$RC from within the designated core area, 
the address pair +(address of call, address of next sequential instruction) is 
generated. 

The calling sequence for this routine is: 


or 


LMJ 

+TRCY$, 

+ 

+ 


11, TRC$ 

trace mode of 0 , 1, or 2 

lower core limit, upper core limit 

storage table address, table length 


T$RC TRCY$, mode lower core limit, upper core limit 

storage table address , table length 


The TRCP$ Standard Interrupt Routine 


This routine sets a one-bit in the user's storage table to show a traced in- 
struction in the designated core area was executed. The table is constructed so 
that each bit of a 36-bit word represents an address relative to the lower core 
limit address. If the indicated table length is exceeded, no storage will occur 
but the trace will be continued. 


If a call to TRCP$ via T$RC is made from within the designated core area, 
a one-bit corresponding to the linkage address is set. 

The calling sequence for this routine is: 


or 


LMJ 

+TRCP$, 

+ 

+ 


11, TRC$ 

trace mode of 0 , 1 or 2 

lower core limit, upper core limit 

storage table address , table length 


T$RC TRCP$, mode lower core limit, upper core limit 
storage table address , table length 


Nested Calls to Interrupt Routines 


It is possible to define a general interrupt routine which can make use of 
the TRCY$ and TRCP$ routines. The following techniques must be used: 
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1. Before using TRCY$ or TRCP$, registers A0 and A1 should contain the 
values of the FROM and TO addresses supplied to the general interrupt 
routine by the trace program. Calls to the standard interrupt routines 
are made by SLJ TRCP$ or SLJ TRCY$. Registers A0 and A1 are al- 
tered before return from these calls. 

2 . Before initiating the trace routine , the required routines TRC Y$ or 
TRCP$ must be initialized by making T$RC calls with the desired stand- 
ard and the general interrupt routine names. The mode and the lower 
and upper core limits must be identical in all calls. Furthermore, the 
linkage initiating the general interrupt routine must be made last. 

Example of Nested Interrupt Routine Usage 


Problem: Find the origin of a jump to location 0. Take the MERR$ exit if 
the instruction is executed. In the continued process of testing, record 
trace information with both TRCY$ and TRCP$. 


Sample 


Solution: T$RC 

TRCY$, 1 010000,010440 


CYBIN, 1000 

T$RC 

TRCP$, 1 010000,010440 


PBIN, 8 

T$RC 

UTRACE,! 010000, 010440 


UTRACE 

J 

$ 



JZ 

13, MERR$ 

TO address = 0, FROM in A0 


s 

12, SAVE 12 



s 

13, SAVE 13 



SLJ 

TRCY$ 



L 

12, SAVE 12 



L 

13, SAVE 13 



SLJ 

TRC P$ 



J 

UTRACE . 

return to trace routine 

SAVE 12 

+0 



SAVE 13 

+0 



CYBIN 

RES 

1000 


PBIN 

RES 
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Description: The first linkage initializes TRCY$ to store FROM-TO ad- 
dress pairs cyclically in table CYBIN. Only 1000 address pairs will be 
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retained. The second linkage initializes TRCP$. The eight cells of 36 
bits each in table PBIN is sufficient to contain all information for the 
designated core limits. The third linkage establishes the user -defined 
routine UTRACE. Since it is the last called, it takes precedence over 
the previous calls without disrupting initialization of TRCY$ and TRCP$. 

At the interrupt for each traced jump instruction, the trace routine 
leaves the origin address of the jump in A0 and the destination address 
in Al. An SU to the users UTRACE is made. The user tests against 
A1 to see if it is zero. If so, the MERR$ exit is taken. A0 is unchanged 
and can be found in the automatic MERR$ thin -film dump. If Al is non- 
zero, the user first saves A0 and Al from future destruction by TRCY$. 
He calls TRCY$ and then restores A0 and Al before calling TRCP$. 
There is no need to restore A0 and Al before returning to the main trace 
program. 

FORTRAN IV Calling Sequences 


In general all trace-initiating calling sequences are in the form: 

CALL NTRC (I, M, $X,$Y, BIN, L) 

All FORIV trace routines are terminated by: 

CALL NTRCX 

All fields of NTRC must be provided. They are interpreted as follows: 
(the mnemonics used are not relevant). 

Field I - a numeric value 1 identifies TRCY$ 

2 identifies TRCP$ 

Field M - a numeric value 0 traces jumps only 

1 traces jumps and skips only 

2 traces all instructions 

Field $X - the statement number corresponding to the lower core limit 
Field $Y - the statement number corresponding to the upper core limit 
Field BIN - name of the array where storage will occur 
Field L - the number of cells available in this array for storage 
Action Taken on Incorrect Parameters 


There is one error condition for which corrective actions are made and 
parameter interpretation continued. If the low core limit and upper core limit 
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are reversed, these are shifted. For all other parameter errors, the desig- 
nated trace routine is not initiated. Instead the console message: 

"**(N)TRC($) CALL ERROR FROM XXXXXX" 

is typed, and control is restored to the calling program. 

The following list summarizes these remaining error conditions: 

1 . Specified core limits do not encompass a portion of core memory 

00000 - 017777 . 

2. Storage table start location is not in core. 

3. Last address of core storage table exceeds location 017777 . 

4. The label identifying the interrupt routine entry point is undefined. 

5. An illegal mode was specified. 

6. Re-entry was attempted without prior use of the trace routine. 

Trace Limitations 


The limitations listed here, which may appear imposing, are normally 
quite remote from the mainstream of normal programs. Most references are 
to I/O interrupts which at worst only reduce the effectiveness of trace and do 
not introduce error conditions. The restrictions are: 

1. Trace may not be initiated with interrupts disabled (i.e. , usually during 
coding) unless the first instruction below the linkage is a PAIJ I/O in- 
terrupt. Without this instruction, the trace routine assumes that inter- 
rupts may be allowed and initially performs a AAIJ. No special coding 
is required to initiate the trace during "main-line coding". 

2. The interrupt "location" MITRC$ is used by the trace. Any attempts to 
change MITRC$ will allow the change, terminate the trace, and return 
control to the main program without introducing errors . Such a condi- 
tion results when an unsolicited "E" key-in or MERR$, MXXX$, 

MEXIT$ (or monitor equivalent) exit occurs. 

3. The trace routine will not trace I/O interrupts. The real-time clock in- 
terrupt is in this class. However, once the interrupt has been proc- 
essed, the trace will resume at the interrupted instruction. 
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4. All I/O interrupts which interrupt the trace routine must restore control 
with interrupts allowed. (All monitor resident and library routines are 
written in this manner.) 

5 . Jumps to the trace routine which are themselves traced will first turn 
off the trace before being executed. Subsequent logic depends on the en- 
try point. 

6. The trace routine is vulnerable to being overwritten by erroneous pro- 
grams. However, it cannot be overlaid by a MAP because it resides in 
independent core. 

7 . All registers other than A0 and A1 used in the general interrupt routine 
must be saved and restored before re-entry to the trace routine. 

8 . The address saved in parking register R3 after a traced repeated se- 
quence will be the location of an execute remote instruction in the trace 
routine itself. 

9. If an error interrupt occurs, the address of the offending instruction will 
be the same location mentioned in item 8 only if the interrupt location 
contains an EX instruction ultimately referencing an LMJ or SU. 

10. If an error interrupt location contains an PAIJ or an EX ultimately ref- 
erencing it, interrupts are prevented belatedly (that is, interrupts are 
allowed first by the trace routine but prevented before the next main 
program instruction is executed). 

11. Error interrupt locations containing jumps must not require indirect 
addressing, B-loop modifications, or B-box incrementation. Should 
these conditions arise , the trace routine will not be able to recognize 
an error interrupt. Further errors may result. 

12. Error interrupts occuring in the user's interrupt routine or from I/O 
interrupt coding are not traced but proceed according to the logic of the 
monitor system. 

Trace Program Logic 


To provide complete information, an adequate trace program must contain 
a software trace to complement the 1107 hardware trace facility. The software 
component of this routine saves register R3 (normally used to hold memory 
lockout information) from destruction by the trace interrupt; prevents I/O 
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interrupts at critical phases, to assure no changes in R3 can be made during in- 
terrupt coding; obtains the address of all traced MOJP instructions (not provided 
by hardware); and detects all instructions executing skips. 

The software trace component performs these duties in the following se- 
quence: 

1. Establishes address of next sequential instruction 

2. Prevents all I/O interrupts 

3. Saves contents of register R3 

4. Obtains operation code of next sequential instruction, and performs 
special functions on an exceptional set of operations 

5 . Restores all thin film registers used by the trace routine 

6. Establishes hardware trace mode 

7 . Executes remotely on next sequential instruction 

8 . If the instruction was not a jump , sets switch to show if a skip was 
executed 

9. Saves R3 in event it was changed by a load or store 

10. Jumps to routines to process all non-jump instructions 


The exceptional set of operations occurs principally because of limitations 
placed upon executing remotely or by the I/O scheme used by the trace routine. 
Specifically , instructions SLJ and LMJ must not be executed remotely by the 
trace routine, for the return address would be incorrect. The instructions 
PAIJ and AAIJ must be sensed in order to inform later parts of the program to 
leave I/O in the desired state. Also, AAIJ must not be performed then but must 
be delayed until the trace interrupt occurs. Tests for nesting of instruction EX 
must be made to assure that previously mentioned instructions are not obscured 

The hardware component of the trace routine performs the following tasks: 

1. Restores R3, which was destroyed by trace interrupt 
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2. Restores I/O interrupt state to that expected by traced program 

3. Obtains the destination address of the traced jump, and performs 
special functions on an exceptional set 

4. Determines if the jump was intended as an entry into trace routine 
itself; if so, allows it 

5. Determines if the jump origin or destination address is in user’s core; 
if so, calls interrupt coding 

6. Transfers control back to the software trace component 


Among the exceptional destination addresses are MREA$ and MSEA$. If a 
jump to MSEA$ or MREA$ is made, and if a request is made to reset MIALL$ 
(all error actions) or to change MITRC$ alone (the trace location) , all thin film 
is restored to that expected by the external program, and tracing is terminated 


The other exceptional addresses are concerned with error interrupt desti- 
nations. If a match of the intended destination of an instruction to the BHIU- 
fields of the instruction in an error interrupt location is found, it is assumed an 
error interrupt just occurred. Special testing and correcting procedures are 
then followed to ensure that the true error address is reported to the error 
routine, rather than the address of the execute remote in the trace program. 
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APPENDIX: 


TRACE ROUTINE FLOW DIAGRAMS 
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